El Mac 9/El Mac 9.iso/Analizado en EL MAC/Updater/Print2Pict 3.7.1/Sourcesƒ/P2PX.h

C/C++ Source or Header | 1996-07-09 | 15.8 KB | 428 lines | [TEXT/CWIE]

#pragma once        // new method of ensuring file is included only once
#define _H_P2PX        // old method

//
//    File P2PX.h
//    © B.Raoult 1992
//
//    [e-mail]
//
//    How to write a Print2Pict extension:
//    ------------------------------------
//
//    A Print2Pict extension is a code resource of type 'P2PX' id = -8192, in
//    a file of type 'P2PX' and creator 'P2P '. The code entry point is a
//    Pascal function (so extension can be wrote in Pascal or C).
//
//        pascal OSErr main (short msg, P2PXPtr arg);
//
//    The function is called with two parameters: the first is a function
//    selector, the second is a pointer to a parameter block containing
//    various field described later. The function must return noErr if
//    everything was OK, or the code of any errors.
//
//    When the extension is called, the current resource file is set to the
//    extension file.
//
// You can write a 'fat' extension by adding a 'P2Px' id = -8192 to the
// resource file
//
//    Values of the message parameter:
//    ================================
//
//    - kGetFlagsMsg
//    -------------
//
//    This message is sent before opening the Style or the Job dialogs:
//    Print2Pict use the answer to enable or disable some items in the
//    dialogs. You must fill the "flags" with the following values:
//
//    if  kEnvironmentOk is not set, the name of the extension is disabled in
//    the popup menu. It cannot be selected by the user. You must clear this
//    bit if your extension requires system features that are not available
//    on this machine. (Color QuickDraw, ...)
//
//    if kWantFileNames is set, Print2Pict will generate a filename for
//    every page printed and pass it to you in the "fsspec" and "script"
//    fields of the argument when sending the kPutPageMsg message. This name
//    either automatically generated or was specified by the user according
//    to the user choice in the Print2Pict options dialog. Use the "creator"
//    field to create the files. If you want only one file name, clear the
//    kWantFileNames bit once you have received the first kPutPageMsg
//    message.
//
//    if kHasOwnPageSize is set, Print2Pict will look for a PREC resource
//    id = 3 in your resource file to setup the Style dialog. A maximum of 5
//    page sizes can be displayed (the sixth is reserved for the custom paper
//    size). When this bit is set, the external cannot be selected in the Job
//    dialog, as an other size may have been chosen in the Style dialog.
//
//    if kHasOwnOptions is set, your external must provide a DITL resource
//    id = -8192, and ICON resource id = -8192 and optionally a cicn resource
//    id = -8192. The ICON (or cicn) is displayed in the options dialog. If
//    the user click on it, the DITL is then appended to the dialog. Your
//    external must respond to the kOptOpenMsg, kOptEventMsg, kOptItemMsg and
//    kOptDoneMsg messages.
//
//    if kOnlyBlackAndWhite is set, Print2Pict will create black and white
//    picture.
//
//    if kCanPreview is set the user can preview the pages before they are
//    disposed. If you provide a resource PREV id = -8192 containing a pascal
//    string that will be use to change the title of the disposition button
//    in the preview dialog.
//
//    if kCanSpool is set, Print2Pict may spool the picture to a file if the
//    memory is too low. The spooled field is set, spooledfile contains the
//    filespec of the spooled picture (PICT format). [NOT YET IMPLEMENTED]
//
//    if kNeedLock is set, the extension is locked before the 'kInitMsg' and
//    'kOptOpenMsg' and released after the 'kEndMsg' and the 'kOptDoneMsg'. This
//    is if you want to install some patches, system callbacks (like dialog items
//    drawing routines),... But when these routines callbacks are called, the
//    current resource file may not be yours, so save it somewhere. [FROM VERSION 3.6 ONLY]
//
//    When entering your routine the "flags" field is set with the
//    kDefaultFlags values (kEnvironmentOk + kWantFileNames + kCanPreview).
//
//    The kGetFlagsMsg message is also sent when the application calls
//    PrOpenDoc, before sending the kInitMsg, to check if the kEnvironmentOk
//    is still set.
//
//    Don't use any fields of the argument other than the "flags" field.
//
//    - kInitMsg
//    ---------
//
//    The message is sent when the application calls PrOpenDoc. If you need
//    some local storage, allocate a handle, and put it in the "data" field
//    of the argument.
//
//    - kEndMsg
//    --------
//
//    The message is sent when the application calls PrCloseDoc. You must free
//    any memory allocated, close any opened file.
//
//    Always check the "data" field before calling DisposHandle.
//
//    - kPutPageMsg
//    ------------
//
//    The message is sent when the application calls PrClosePage. This is
//    where you must process the picture.
//
//            "error"        is the last error.
//            "page"      contains the current page number. (Starting from 1)
//            "pict"      contains a handle on the picture of the current page.
//            "docName"   is the name of the printed document (can be empty).
//            "appName"   is the name of the current application.
//
//    If kWantFileNames is set in the "flags" field: "fsspec"  is the file
//    spec where the page is to be saved, and "script"  the scriptcode to use
//    with FSpCreate.
//
//    If kCanSpool is set in the "flags" field, Print2Pict may spool the
//    picture to disk if the memory is low. [NOT YET IMPLEMENTED] "pict" is
//    the set to NULL, "spooled" is true, and "spoolfile" contains the file
//    spec of the file where the picture is spooled (PICT format)
//
//    - kNewPageMsg ( added with version 3.4 of Print2Pict )
//    ------------
//
//    The message is sent when the application calls PrOpenPage. The current
//    port is the printing port and OpenPicture has been called.
//
//            "error"        is the last error.
//            "page"      contains the current page number. (Starting from 1)
//            "docName"   is the name of the printed document (can be empty).
//            "appName"   is the name of the current application.
//
//
//    - kOptOpenMsg
//    ------------
//
//    To receive this message the kHasOwnOptions bit must be set. Print2Pict
//    display the DITL you provide and calls the external. You can allocate
//    some private storage in the "data" field. You must initialize the
//    dialog items here. "dlog" is the dialog containing your items, "skip"
//    is the number of items in this dialog belonging to Print2Pict.
//
//             IMPORTANT NOTE: Before version 3.6, there was a bug that prevented
//            PICT, ICON and CNTL items in the dialogs. This bug is fixed.
//
//    - kOptEventMsg
//    -------------
//
//    To receive this message the kHasOwnOptions bit must be set. The
//    external is called from the ModalDialog filter procedure.
//
//    "dlog" is the dialog containing your items, "skip" is the number of
//    items in this dialog belonging to Print2Pict. "event" is the events
//    that triggered the call, "itemHit" is the item passed to the filter
//    procedure, "retcode" must be set to true if "itemHit" was changed. See
//    InsideMac I page 415 for more details about the filter procedure.
//
//    - kOptItemMsg
//    ------------
//
//    To receive this message the kHasOwnOptions bit must be set. The
//    external is called with the item returned by ModalDialog. You must
//    update the check boxes and the radio buttons. "item" is the value
//    return by ModalDialog. "dlog" is the dialog containing your items,
//    "skip" is the number of items in this dialog belonging to Print2Pict.
//    The dialog item "skip" is a static text you can use to display any
//    messages.
//
//    - kOptDoneMsg
//    ------------
//
//    To receive this message the kHasOwnOptions bit must be set. Print2Pict
//    calls the external before removing the DITL from the dialog. You must
//    get the new values of the dialog items, and release any allocated
//    memory. "dlog" is the dialog containing your items, "skip" is the
//    number of items in this dialog belonging to Print2Pict.
//
//    Values of the P2PXPtr parameter:
//    ================================
//
//    For every calls, a parameter is passed to the extension. All field are
//    read only except "flags" and "data".
//
//    Print2Pict fills the block with zeros and then sets the fields. So you
//    are sure that missing fields are set to zero:
//
//    ALWAYS CHECK A POINTER (OR HANDLE) FIELD AGAINST NULL BEFORE
//    DEREFERENCING IT.
//
//    This is a description of the field of the parameter block using the
//    format - name (type) [list of messages for which the field is valid]
//
//    - vers (short) [all]
//    --------------------
//
//    Print2Pict version, the low byte contains the major version (3 at
//    present). The high byte containt the minor version (4 now). They are
//    swapped for compatibility with version 3.0. Use the P2PVERSION macro
//    to get the version in BCD (i.e vers 3.5 is 0x305)
//
//    - port (TPPrPort) [kPutPageMsg,kNewPageMsg]
//    -----------------------------------------
//
//        Current print graph port.
//
//    - hPrint (THPrint) [kPutPageMsg,kNewPageMsg]
//    ------------------------------------------
//
//        Current print record.
//
//    - page (short) [kPutPageMsg,kNewPageMsg]
//    --------------------------------------
//
//        Current page number (starting from 1).
//
//    - pict (PicHandle) [kPutPageMsg]
//    -------------------------------
//
//        Picture of the current page. If NULL, then the picture was spooled (see
//        spooled and spoolfile)
//
//    - color (Boolean) [kPutPageMsg,kNewPageMsg]
//    -----------------------------------------
//
//        Set to true if the print grafport is the color port.
//
//    - flags (long) [all]
//    --------------------
//
//        Set by the extension. See previous paragraph.
//
//    - error (OSErr) [all]
//    --------------------
//
//        Last error reported by Print2Pict.
//
//    - data (Handle) [kInitMsg,kPutPageMsg,kEndMsg,kNewPageMsg]
//                    [kOptOpenMsg,kOptEventMsg,kOptItemMsg,kOptDoneMsg if kHasOwnOptions]
//    ---------------------------------------------------------------------------------
//
//        Put here a handle to your private storage. Alocate it when
//        you receive kInitMsg or kOptOpenMsg, free it when you receive kEndMsg or kOptDoneMsg.
//
//    - docName (Str255) [kInitMsg,kPutPageMsg,kEndMsg,kNewPageMsg]
//    ---------------------------------------------------------
//
//        Name of the printed document.
//
//    - appName (Str255) [kInitMsg,kPutPageMsg,kEndMsg,kNewPageMsg]
//    ---------------------------------------------------------
//
//        Name of the current application.
//
//    - fspec (FSSpec) [kPutPageMsg if kWantFileNames]
//    ------------------------------------------------
//
//        File spec. where to save the picture to.
//
//    - script (ScriptCode) [kPutPageMsg if kWantFileNames]
//    -----------------------------------------------------
//
//        script code of fspec (needed for FSpCreate).
//
//    - creator (OSType) [all]
//    ------------------------
//
//        creator choosen by the user in the Print2Pict options dialog.
//
//    - spooled (Boolean) [kPutPageMsg if kCanSpool] [NOT YET IMPLEMENTED]
//    -------------------------------------------------------------------
//
//        true if the picture was spooled.
//
//    - spoolfile (FSSpec) [kPutPageMsg if kCanSpool] [NOT YET IMPLEMENTED]
//    --------------------------------------------------------------------
//
//        file spec of the spooled picture (PICT file). set if spooled is true.
//
//    - dlog  (DialogPtr) [kOptOpenMsg,kOptEventMsg,kOptItemMsg,kOptDoneMsg if kHasOwnOptions]
//    -------------------------------------------------------------------------------------
//
//        Dialog where the your DITL is displayed.
//
//    - event (EventRecord*) [kOptEventMsg if kHasOwnOptions]
//    -------------------------------------------------------
//
//        Event received in ModalDialog filter procedure.
//
//    - itemHit (short*) [kOptEventMsg if kHasOwnOptions]
//    ---------------------------------------------------
//
//        Item received in ModalDialog filter procedure.
//
//    - retcode (Boolean) [kOptEventMsg if kHasOwnOptions]
//    ----------------------------------------------------
//
//        Return code of ModalDialog filter procedure.
//
//    - skip (short) [kOptOpenMsg,kOptEventMsg,kOptItemMsg,kOptDoneMsg if kHasOwnOptions]
//    --------------------------------------------------------------------------------
//
//        Number of items belonging to Print2Pict in the dialog.
//
//    - item (short) [kOptItemMsg if kHasOwnOptions]
//    ----------------------------------------------
//
//        Item number returned by ModalDialog.
//
//    Help:
//    =====
//
//    To provide somme help to the user, add a TEXT resource id = -8192 and an
//    optional styl resource, same id. The text will be displayed in the Help
//    window.
//
//    Ideas:
//    ======
//
//    Here are some ideas of extensions:
//
//        - Print to Movie (QuickTime) each page is a frame.
//        - HyperPrint (HyperCard) each page is a card. Has its own paper format (the
//          size of a card.
//        - Print to RTF, Print to Word, ... all text formats.
//        - Print to PCX, GIF, all PC stuff, ....
//        - Print to X, XWindows Pixmaps.
//
//        You are welcome to send me any extensions you write, so I can add them to
//        the next releases of Print2Pict.
//

#ifndef __PRINTING__
#    include <Printing.h>
#endif

#ifndef __FILES__
#    include <Files.h>
#endif

//============================ Messages =====================================

enum {
    kNoMsg,
    kGetFlagsMsg,
    kInitMsg,
    kEndMsg,
    kPutPageMsg,
    kOptOpenMsg,
    kOptEventMsg,
    kOptItemMsg,
    kOptDoneMsg,
    kNewPageMsg
};

//=============================== Flags =====================================

enum {
    kEnvironmentOk        = 1 << 0, // Set if machine OK (i.e. has color QD,...)
    kWantFileNames        = 1 << 1, // If code resource need file names
    kHasOwnPageSize        = 1 << 2, // If the code has its own page size
    kCanPreview            = 1 << 3, // Pages can be previewed before disposed
    kHasOwnOptions        = 1 << 4, // If code has own options dialog
    kOnlyBlackAndWhite    = 1 << 5, // No color pictures
    kCanSpool            = 1 << 6, // Can use spooled pictures
    kNeedLock            = 1 << 7  // The extension is locked between calls, new in version 3.6
};

#define kDefaultFlags       (kEnvironmentOk+kWantFileNames+kCanPreview)

#define P2PVERSION(arg)        ((arg->vers >> 8) + ((arg->vers & 0xf) << 8))

//============================= Parameter block =============================

typedef struct
{
    short       vers;       // Print2Pict major version (3 now)
    TPPrPort    port;       // Print graphport
    THPrint     hPrint;     // Print record
    short       page;       // Current page
    PicHandle   pict;       // Content of page
    Boolean     color;      // The printport is a color port
    long        flags;      // Code flags
    Handle      data;       // Free to use
    OSErr        error;        // Last error code
    Str255      docName;    // Name of printed document
    Str255      appName;    // Name of current application
    FSSpec      fspec;      // File spec if kWantFileNames
    ScriptCode  script;     // Script code if kWantFileNames
    OSType      creator;    // user chosen creator
    Boolean     spooled;    // Picture was spooled
    FSSpec      spoolfile;  // Spolled picture

    // for options dialog

    DialogPtr   dlog;       // The options dialog
    EventRecord *event;     // Event received in ModalDialog filter proc
    short       *itemHit;   // Item received in ModalDialog filter proc
    Boolean     retcode;    // Retcode of ModalDialog filter proc
    short       skip;       // Number of items belonging to Print2Pict
    short       item;       // Item number returned by modal dialog
}
P2PXRec, *P2PXPtr;

//============================= UUP For fat resource =============================
enum {
    uppP2PXEntryProcInfo = kPascalStackBased
         | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
         | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(short)))
         | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(P2PXPtr)))
};

#ifndef BuildingP2P
#ifdef powerc
pascal  OSErr main(short msg,P2PXPtr arg);

// Don't change this name
RoutineDescriptor    P2PX = BUILD_ROUTINE_DESCRIPTOR(uppP2PXEntryProcInfo, main);
#endif
#endif